
# 📋 MQTT Playlist 指令文档

## 基本信息
- **主题路径**: `/SANDART001/{设备SN}/command`
- **响应主题**: `/SANDART001/{设备SN}/response`
- **基本格式**: JSON

## 🎵 Playlist 指令总览

### 1. 📋 **list** - 获取播放列表

**请求格式**:
```json
{
  "cmd": "playlist",
  "data": {
    "action": "list"
  }
}
```

**响应格式**:
```json
{
  "cmd": "playlist",
  "action": "list",
  "status": "success",
  "timestamp": 12345678,
  "device_sn": "680766215788",
  "data": {
    "total_count": 3,
    "current_index": 1,
    "patterns": [
      {
        "index": 0,
        "file_name": "pattern1.thr",
        "display_name": "pattern1",
        "is_current": false
      },
      {
        "index": 1,
        "file_name": "pattern2.thr",
        "display_name": "pattern2",
        "is_current": true
      },
      {
        "index": 2,
        "file_name": "pattern3.thr",
        "display_name": "pattern3",
        "is_current": false
      }
    ]
  }
}
```

### 2. ➕ **add** - 添加图案到播放列表

**请求格式**:
```json
{
  "cmd": "playlist",
  "data": {
    "action": "add",
    "patterns": [
      {"file_name": "new_pattern.thr"},
      {"file_name": "another_pattern.thr"}
    ]
  }
}
```

**支持的patterns格式**:
- **对象格式**: `{"file_name": "pattern.thr"}`
- **字符串格式（文件名）**: `"pattern.thr"`
- **字符串格式（URL）**: `"https://example.com/pattern.thr"`

**响应格式**:
```json
{
  "cmd": "playlist",
  "action": "add",
  "status": "success",
  "timestamp": 12345678,
  "device_sn": "680766215788",
  "message": "Added 2 patterns to playlist"
}
```

### 3. ➖ **remove** - 从播放列表移除图案

**请求格式**:
```json
{
  "cmd": "playlist",
  "data": {
    "action": "remove",
    "patterns": [
      {"file_name": "pattern_to_remove.thr"},
      {"file_name": "another_pattern.thr"}
    ]
  }
}
```

**响应格式**:
```json
{
  "cmd": "playlist",
  "action": "remove",
  "status": "success",
  "timestamp": 12345678,
  "device_sn": "680766215788",
  "message": "Removed 2 patterns from playlist"
}
```

### 4. 🧹 **clear** - 清空播放列表并删除所有THR文件

**请求格式**:
```json
{
  "cmd": "playlist",
  "data": {
    "action": "clear"
  }
}
```

**功能说明**:
- 删除 `/patterns` 目录下的所有 `.thr` 文件
- **保护机制**: 如果当前正在绘图，会保留正在绘图的图案文件
- 自动重新加载播放列表状态

**响应格式**:
```json
{
  "cmd": "playlist",
  "action": "clear",
  "status": "success",
  "timestamp": 12345678,
  "device_sn": "680766215788",
  "message": "Pattern files deleted and playlist cleared (current drawing pattern preserved)"
}
```

### 5. ▶️ **playNow** - 立即播放（清空并添加新图案）

**请求格式**:
```json
{
  "cmd": "playlist",
  "data": {
    "action": "playNow",
    "patterns": [
      {"file_name": "immediate_pattern.thr"}
    ]
  }
}
```

**功能说明**:
- 清空当前播放列表
- 添加新的图案
- 设置为当前播放

**响应格式**:
```json
{
  "cmd": "playlist",
  "action": "playNow",
  "status": "success",
  "timestamp": 12345678,
  "device_sn": "680766215788",
  "message": "Playing 1 patterns now"
}
```

## 🔄 状态更新

每次playlist操作后，系统会自动发布播放列表状态更新到 `/SANDART001/{设备SN}/response` 主题。

## ❌ 错误响应格式

```json
{
  "cmd": "playlist",
  "action": "add",
  "status": "error",
  "timestamp": 12345678,
  "device_sn": "680766215788",
  "message": "Missing patterns data"
}
```

## 🔧 常见错误类型

- `"Missing patterns data"` - 缺少patterns字段
- `"Patterns array is empty"` - patterns数组为空
- `"No valid patterns found"` - 没有找到有效的图案
- `"PatternLoader not available"` - 图案加载器不可用
- `"Unknown playlist action: {action}"` - 未知的操作类型

## 💡 使用示例

### 基本操作流程:
1. **获取当前列表**: `{"cmd": "playlist", "data": {"action": "list"}}`
2. **添加新图案**: `{"cmd": "playlist", "data": {"action": "add", "patterns": [{"file_name": "new.thr"}]}}`
3. **清空所有**: `{"cmd": "playlist", "data": {"action": "clear"}}`

### URL下载示例:
```json
{
  "cmd": "playlist",
  "data": {
    "action": "add",
    "patterns": [
      "https://example.com/remote_pattern.thr"
    ]
  }
}
```
